{
 "metadata": {
  "signature": "sha256:4adee79c3a0fcc23c0a0e3ed3e1c4a981b2b48149aff995cffd276515454c034"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Scripting Mayavi 2: basic modules\n",
      "======================================================================\n",
      "\n",
      "Introduction\n",
      "------------\n",
      "\n",
      "These modules are called \"basic\" because they are general and\n",
      "independant to all kind of data.\n",
      "\n",
      "Before using a module, remind that you have to import it.\n",
      "\n",
      "In general, if you want to change the color of an object, you have to\n",
      "type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "module.actor.property.color = fg_color"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "where fg\\_color is a \"tuple\", say (0, 0, 0) for black.\n",
      "\n",
      "Note: You can set color for each module/filter (when available, of\n",
      "course), as above. But you can also set background/foreground colors for\n",
      "all your !MayaVi2 sessions. See [:Cookbook/MayaVi/Tips:\n",
      "Cookbook/MayaVi/Tips]. So, your background and foreground colors may (in\n",
      "fact, must) be different from those in the pictures presented here.\n",
      "\n",
      "Outline module\n",
      "--------------\n",
      "\n",
      "Nothing special for this very simple module.\n",
      "\n",
      "Begin to import the Outline module:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.outline import Outline"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "then"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fg_color = (0, 0, 0)    # black foreground color\n",
      "o = Outline()\n",
      "script.add_module(o)\n",
      "o.actor.property.color = fg_color"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_outline.png\n",
      "\n",
      "Axes module\n",
      "-----------\n",
      "\n",
      "For axis, you can set several parameters:\n",
      "\n",
      "`*\u00a0color\u00a0for\u00a0axes;`\\\n",
      "`*\u00a0color\u00a0for\u00a0labels;`\\\n",
      "`*\u00a0labels\u00a0name;`\\\n",
      "`*\u00a0and\u00a0label\u00a0format.`\n",
      "\n",
      "Here's what you can type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.axes import Axes"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "then"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "a = Axes()\n",
      "script.add_module(a)\n",
      "a.axes.property.color = fg_color                     # color for axes\n",
      "a.axes.axis_title_text_property.color = fg_color     # color for axes title\n",
      "a.axes.x_label = \"Lx\"                                # label for Ox axis\n",
      "a.axes.y_label = \"Ly\"                                # label for Oy axis\n",
      "a.axes.z_label = \"Lz\"                                # label for Oz axis\n",
      "a.axes.label_format = \"\"                             # no dimensions displayed\n",
      "a.axes.axis_label_text_property.color = fg_color     # in case we want to display them"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Label format is the format for the dimensions along Ox, Oy and Oz axis.\n",
      "By default, it is set to %6.3g.\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_axes.png\n",
      "\n",
      "OrientationAxes module\n",
      "----------------------\n",
      "\n",
      "!OrientationAxes module will display a little trihedron in the corner of\n",
      "the render window, showing the orientation of the three axes, Ox, Oy,\n",
      "Oz.\n",
      "\n",
      "Note: VTK \\> 5.0 must be installed in order to use this module.\n",
      "\n",
      "Nothing special here, as the Outline module, you can set the labels\n",
      "color:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.orientation_axes import OrientationAxes"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "oa = OrientationAxes()\n",
      "script.add_module(oa)\n",
      "oa.text_property.color = fg_color"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_orientationaxes.png\n",
      "\n",
      "Text module\n",
      "-----------\n",
      "\n",
      "You can use this module to display a title for your rendering window.\n",
      "\n",
      "You need a text (a string), and you have to set up its position in the\n",
      "window (coordinates go from 0 to 1 in x and y) with the x\\_position and\n",
      "y\\_position parameters.\n",
      "\n",
      "Then you can set up the height and the width of your text:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.text import Text"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# I like my title centered and at top of the window\n",
      "t = Text()\n",
      "t.text = \"My Title Centered at the Top\"\n",
      "script.add_module(t)\n",
      "t.actor.scaled_text = False\n",
      "t.actor.text_property.font_size = 34\n",
      "t.actor.text_property.color = fg_color\n",
      "# have to find out text width to center it. Tricky, but works fine. Thanks to Prabhu.\n",
      "t.width = 1.0*t.actor.mapper.get_width(t.scene.renderer)/t.scene.renderer.size[0]\n",
      "height = 1.0*t.actor.mapper.get_height(t.scene.renderer)/t.scene.renderer.size[1]\n",
      "t.x_position = 0.5-t.width/2\n",
      "t.y_position = 1-height"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_title.png\n",
      "\n",
      "Now, we will present how to set up the color bar, called \"scalar\" or\n",
      "\"vector\" color bar. It depends of the data you have in your file.\n",
      "\n",
      "Setting up color bar\n",
      "--------------------\n",
      "\n",
      "Strictly speaking, the color bar is not a module, i.e. you don't need to\n",
      "add it with an add\\_module() command: you have to associate the\n",
      "\"module\\_manager\" object to a module, previously loaded, say the Text\n",
      "module for example.\n",
      "\n",
      "Then, you can configure the color bar as follows (keywords are\n",
      "self-explanatory):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mmsclut = t.module_manager.scalar_lut_manager\n",
      "mmsclut.show_scalar_bar = True\n",
      "mmsclutsc = mmsclut.scalar_bar\n",
      "mmsclutsc.orientation = \"vertical\"    # or \"horizontal\"\n",
      "mmsclutsc.width = 0.1\n",
      "mmsclutsc.height = 0.8\n",
      "mmsclutsc.position = (0.01, 0.15)     # color bar located to the left of the rendering window\n",
      "mmsclutsc.label_text_property.color = fg_color\n",
      "mmsclutsc.title_text_property.color = fg_color\n",
      "mmsclut.number_of_labels = 10\n",
      "mmsclut.number_of_colors = 64\n",
      "mmsclut.data_name = \"My Label\""
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_colorbar.png\n",
      "\n",
      "Note: To configure a color bar for vectors instead of scalars, replace\n",
      "\"scalar\\_lut\\_manager\" by \"vector\\_lut\\_manager\" above.\n",
      "\n",
      "At last, to close the \"basic\" modules section, let's see how we can\n",
      "setting up the scene.\n",
      "\n",
      "Setting up the scene\n",
      "--------------------\n",
      "\n",
      "By \"setting up the scene\", you have to read \"how the scene will be\n",
      "seen\": for example, setting the color background and the point of view\n",
      "of the scene.\n",
      "\n",
      "As usual, setting these parameters using python & TVTK is very easy.\n",
      "\n",
      "If you want to change background color, you may need to also change\n",
      "foreground color for all modules. We recall them here."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#! /usr/bin/env python\n",
      "\n",
      "from enthought.mayavi.modules.outline import Outline\n",
      "from enthought.mayavi.modules.axes import Axes\n",
      "from enthought.mayavi.modules.orientation_axes import OrientationAxes\n",
      "from enthought.mayavi.modules.text import Text\n",
      "\n",
      "# we want a dark foreground color on a bright background\n",
      "fg_color = (0.06666, 0.06666, 0.1804)   # dark blue\n",
      "bg_color = (1, 1, 0.94118)              # ivory\n",
      "\n",
      "# setting foreground color for Outline module\n",
      "o = Outline()\n",
      "script.add_module(o)\n",
      "o.actor.property.color = fg_color\n",
      "\n",
      "# setting foreground color for Axes module\n",
      "a = Axes()\n",
      "script.add_module(a)\n",
      "a.axes.property.color = fg_color                     # color for axes\n",
      "a.axes.axis_title_text_property.color = fg_color     # color for axes label\n",
      "a.axes.x_label = \"Lx\"                                # label for Ox axis\n",
      "a.axes.y_label = \"Ly\"                                # label for Oy axis\n",
      "a.axes.z_label = \"Lz\"                                # label for Oz axis\n",
      "a.axes.label_format = \"\"                             # no dimensions displayed\n",
      "\n",
      "\n",
      "# setting foreground color for OrientationAxes module\n",
      "oa = OrientationAxes()\n",
      "script.add_module(oa)\n",
      "oa.text_property.color = fg_color\n",
      "\n",
      "# setting foreground color for Text module\n",
      "t = Text()\n",
      "t.text = \"My Title Centered at the Top\"\n",
      "script.add_module(t)\n",
      "t.actor.scaled_text = False\n",
      "t.actor.text_property.font_size = 34\n",
      "t.actor.text_property.color = fg_color\n",
      "t.width = 1.0*t.actor.mapper.get_width(t.scene.renderer)/t.scene.renderer.size[0]\n",
      "height = 1.0*t.actor.mapper.get_height(t.scene.renderer)/t.scene.renderer.size[1]\n",
      "t.x_position = 0.5-t.width/2\n",
      "t.y_position = 1-height\n",
      "\n",
      "# setting foreground color for labels and title color bar.\n",
      "mmsclut = t.module_manager.scalar_lut_manager\n",
      "mmsclut.show_scalar_bar = True\n",
      "mmsclutsc = mmsclut.scalar_bar\n",
      "mmsclutsc.orientation = \"vertical\"\n",
      "mmsclutsc.width = 0.1\n",
      "mmsclutsc.height = 0.8\n",
      "mmsclutsc.position = (0.01, 0.15)\n",
      "mmsclutsc.label_text_property.color = fg_color\n",
      "mmsclutsc.title_text_property.color = fg_color\n",
      "mmsclut.number_of_labels = 10\n",
      "mmsclut.number_of_colors = 64\n",
      "mmsclut.data_name = \"My Label\"\n",
      "\n",
      "# setting background color for the scene.\n",
      "t.scene.background = bg_color"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Some points of view are also predefined in !MayaVi2.\n",
      "\n",
      "If you want:\n",
      "\n",
      "`*\u00a0Ox\u00a0axis\u00a0normal\u00a0to\u00a0the\u00a0scene:\u00a0use\u00a0x_plus_view()\u00a0(towards)\u00a0or\u00a0x_minus_view()\u00a0(backwards)\u00a0method;`\n",
      "\n",
      "`*\u00a0Oy\u00a0axis\u00a0normal\u00a0to\u00a0the\u00a0scene:\u00a0use\u00a0y_plus_view()\u00a0(towards)\u00a0or\u00a0y_minus_view()\u00a0(backwards)\u00a0method;`\n",
      "\n",
      "`*\u00a0Oz\u00a0axis\u00a0normal\u00a0to\u00a0the\u00a0scene:\u00a0use\u00a0z_plus_view()\u00a0(towards)\u00a0or\u00a0z_minus_view()\u00a0(backwards)\u00a0method;`\n",
      "\n",
      "`*\u00a0an\u00a0isometric\u00a0view\u00a0(coordinates\u00a0normal\u00a0are\u00a0(1,\u00a01,\u00a01)),\u00a0use\u00a0isometric_view\u00a0method.`\n",
      "\n",
      "You can also:\n",
      "\n",
      "`*\u00a0set\u00a0the\u00a0elevation\u00a0and\u00a0azimuth\u00a0angles\u00a0to\u00a0your\u00a0needs\u00a0(in\u00a0degrees);`\n",
      "\n",
      "`*\u00a0set\u00a0a\u00a0zooming\u00a0factor\u00a0of\u00a0your\u00a0scene.`\n",
      "\n",
      "with:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "t.scene.x_plus_view()\n",
      "t.scene.camera.azimuth(62)\n",
      "t.scene.camera.elevation(19.5)\n",
      "t.scene.camera.zoom(1.5)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "At last, you can choose if you want a perspective view or a parallel\n",
      "projection for your scene:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "t.scene.camera.parallel_projection = True"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_scene_parall.png\n",
      "\n",
      "for a parallel projection, or:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "t.scene.camera.parallel_projection = False"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_BasicModules/basic_scene_persp.png)\n",
      "\n",
      "for a perspective view.\n",
      "\n",
      "Here, \"t\" stands for the Text module previously loaded.\n",
      "\n",
      "Note: There are a lot of others parameters you can set up for your scene. See [:Cookbook/MayaVi/Tips: Cookbook/MayaVi/Tips] to read how to get more information about setting parameters modules.\n",
      "\n",
      "Now, it's time to read the most interesting part: configuring and using modules and filters which interact with your data.\n"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}